Using the Lifecycle Hooks

Lifecycle hooks are an essential part of scripting, allowing you to define behavior at specific points during the lifecycle of an object. By using the lifecycle hooks, you can control when certain logic is executed in relation to the object's existence in the scene.

The scripting runtime supports three main lifecycle hooks:

1. startup

• Purpose: Fired only once when the object is instantiated in the scene, typically when it is created or initialized. This is where you set up your initial state, load resources, or perform any actions that should occur at the start of the object’s lifecycle.

• When to Use: You can use this hook to perform any initialization steps, such as setting the initial position, loading external assets, or preparing the object for interaction.

Example:

function startup() {
// Set initial position of the object
object.setPosition(0, 0, 0);
console.log("Object initialized.");
}

2. update

• Purpose: Fired on every frame as long as the object is active in the scene. This hook allows you to perform continuous updates, such as moving objects, checking user input, or modifying properties based on dynamic conditions (like time or player interaction).

• Parameters:

  • delta: The time in seconds since the last frame (useful for frame-rate independent updates).
  • time: The total time elapsed since the scene started (useful for time-based behavior). When to Use: Use this hook to handle logic that needs to be updated in real time, such as animation, physics updates, and input handling.

• When to Use: Use this hook to handle logic that needs to be updated in real-time, such as animation, physics updates, and input handling.

Example:

function update(delta, time) {
    // Make the object move to the right over time
    let currentPosition = object.getPosition();
    object.setPosition(currentPosition.x + 1 * delta, currentPosition.y, currentPosition.z);
}

3. dispose

• Purpose: Fired when the object is destroyed or removed from the scene. This hook is essential for cleaning up any resources, stopping ongoing processes, or performing any finalization logic.

• When to Use: You can use this hook to free up memory, stop animations or timers, or save any data that needs to persist after the object is removed from the scene.

Example:

function dispose() {
    // Clean up resources before the object is destroyed
    console.log("Object is being destroyed. Cleaning up.");
    object.stopAnimations();
    object.removeEventListener('click', onClick);
}

Define the Lifecycle Hooks

You can connect your script to lifecycle events by defining lifecycle hooks using the #pragma lifecycle preprocessor directive. This directive allows your script to respond to key moments in an object's lifecycle, such as initialization, updates during the scene, and destruction.

Here’s an example that demonstrates how to use all three lifecycle hooks within a script:

#pragma lifecycle(startup, update, dispose)
function startup() {
    // Setup code here
}
function update(delta, time) {
    // Continuous logic (e.g., movement, animations)
}
function dispose() {
    // Cleanup code here (e.g., remove event listeners, stop animations)
}

Aliases for Lifecycle Hooks

One of the great features of the scripting runtime is the ability to use aliases. This allows you to assign custom names to your lifecycle functions, making your code more readable or better suited to your naming conventions. For instance, if you want to use custom names for the hooks like start or onActivate instead of the default startup, you can define an alias using the following syntax:

#pragma lifecycle(startup=start, update=updateLoop, dispose=cleanup)

In this case:

• start will be the function executed when the object is initialized (startup).
• updateLoop will run on every frame instead of the default update.
• cleanup will be invoked when the object is destroyed (dispose).

This provides flexibility to match the lifecycle functions to your specific naming preferences, ensuring your scripts stay consistent with your project's coding style.